Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

Useful object handles

The properties described in this section return useful object handles to you.

ContainerHandle

This HANDLE property, available for all SmartObjects, is only meaningful for objects that have a window or frame. For a frame-based object, such as a browser or viewer, it returns the frame handle. For a window-based object, such as a SmartWindow, it returns the window handle. Use this handle when you must query or manipulate the attributes of the container widget itself.

BrowseHandle

This HANDLE property returns the browser widget handle for a SmartBrowser. Use this handle when you must query or manipulate the attributes of the browse itself.

BufferHandles and QueryHandle

These two properties return handles from the database query that is used to populate an SDO. The BufferHandles CHARACTER property is a comma-separated list of the handles of the database record buffers the framework uses to populate the SDO temp-table.

The QueryHandle HANDLE property is the handle of the database query. Note that these handles are the database object handles, not SDO temp-table or buffer handles. They are valid only on the server side of a divided SDO, and should be used only in cases where your code must reference the database data as the framework loads it into the temp-table.

QueryRowObject

This HANDLE property returns the buffer handle to the SDO’s temp-table buffer (the RowObject buffer in other words) that holds the data values for the currently selected row in a browser. This can be useful when you must query those values within the ROW-DISPLAY trigger for the browser, for example. The SCREEN-VALUEs of the individual cells cannot be queried within this 4GL event, so in order to write logic that reacts to a cell’s value, by changing the background color or some other attribute of the cell or the row, you must be able to refer back to the underlying data buffer and its fields. See Chapter 1 "Writing Super Procedures for Progress Dynamics Objects" for more information.

Note that the WIDGET-HANDLE is implemented to hide this complexity.

As an example, look at this code from the widgetValue function that is part of the proposed client-side API for retrieving and setting values in dynamic objects from custom super procedures. The variable hField holds the handle to a field from the FieldHandles list, as shown:

IF CAN-QUERY(hField, "FILE-NAME") THEN /* This is a SmartDataField. Return its DataValue property. Note that this is the underlying "key" value that is meaningful to the code, not the "DisplayValue" shown to the user. */ {get DataValue cValue hField}. ELSE IF CAN-QUERY(hField, "SCREEN-VALUE") THEN cValue = hField:SCREEN-VALUE. ELSE DO: {get QueryRowObject hBuffer} NO-ERROR. IF VALID-HANDLE(hBuffer) THEN ASSIGN hField = hBuffer:BUFFER-FIELD(cField) cValue = STRING(hField:BUFFER-VALUE) NO-ERROR. END. /* END ELSE DO IF NOT CAN-QUERY SCREEN-VALUE (Browse) */